Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / lispref.info-30 < prev next >

Wrap

GNU Info File | 1995-09-01 | 49.8 KB | 1,123 lines

This is Info file ../../info/lispref.info, produced by Makeinfo-1.63 from the input file lispref.texi. Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation. Copyright (C) 1995 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English. File: lispref.info, Node: Finding Extents, Next: Extent Properties, Prev: Extent Endpoints, Up: Extents Finding Extents =============== The following functions allow for scanning over the extents in a buffer or searching for extents in a particular range of a buffer. Keep in mind the way that extents are ordered in a buffer (*note Extent Endpoints::.). - Function: next-extent EXTENT Given an extent EXTENT, this function returns the next extent in the buffer's display order. If EXTENT is a buffer, this returns the first extent in the buffer. - Function: previous-extent EXTENT Given an extent EXTENT, this function returns the previous extent in the buffer's display order. If EXTENT is a buffer, this returns the last extent in the buffer. If you want to map over all extents that meet a certain criterion, use `map-extents' - it is much faster than a loop involving `next-extent'. - Function: extent-at POS &optional BUFFER PROPERTY BEFORE This function finds the "smallest" extent (i.e., the last one in the display order) at (i.e., overlapping) POS in BUFFER having PROPERTY set. BUFFER defaults to the current buffer. PROPERTY defaults to `nil', meaning that any extent will do. Returns `nil' if there is no matching extent at POS. If the fourth argument BEFORE is not `nil', it must be an extent; any returned extent will precede that extent. This feature allows `extent-at' to be used by a loop over extents. - Function: map-extents FUNCTION &optional BUFFER FROM TO MAPARG CLOSED-END This function maps FUNCTION over the extents which overlap the region `[FROM, TO)' (or `[FROM, TO]' if CLOSED-END is non-`nil') in BUFFER. FUNCTION is called with the arguments `(extent, MAPARG)'. The arguments FROM, TO, MAPARG, and BUFFER default to the beginning of BUFFER, the end of BUFFER, `nil', and `(current-buffer)', respectively. `map-extents' returns the first non-`nil' result produced by FUNCTION, and no more calls to FUNCTION are made after that. If BUFFER is an extent, FROM and TO default to the extent's endpoints, and the mapping omits that extent and its predecessors. This feature supports restarting a loop based on `map-extents'. The effect of CLOSED-END is that, if an extent and the map region overlap only at a start and end position, the extent is visited by `map-extents' only if both positions are closed. - Function: map-extent-children FUNCTION &optional BUFFER FROM TO MAPARG CLOSED-END This function is similar to `map-extents', but differs in that: * It only visits extents which start in the given region. * After visiting an extent E, it skips all other extents which start inside E but end before E's end. Thus, this function may be used to walk a tree of extents in a buffer: (defun walk-extents (buffer &optional ignore) (map-extent-children 'walk-extents buffer)) - Function: extent-in-region-p EXTENT &optional FROM TO CLOSED-END This function returns T if `map-extents' would visit EXTENT if called with the given arguments. File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Finding Extents, Up: Extents Properties of Extents ===================== Each extent has a property list associating property names with values. Some property names have predefined meanings, and can usually only assume particular values. Assigning other values to such a property either cause the value to be converted into a legal value (e.g., assigning anything but `nil' to a Boolean property will cause the value of `t' to be assigned to the property) or will cause an error. Property names without predefined meanings can be assigned any value. An undefined property is equivalent to a property with a value of `nil', or with a particular default value in the case of properties with predefined meanings. Note that, when an extent is created, the `end-open' and `detachable' properties are set on it. - Function: extent-property EXTENT PROPERTY This function returns the value of PROPERTY in EXTENT. If PROPERTY is undefined, `nil' is returned. - Function: extent-properties EXTENT This function returns a list of all of EXTENT's properties that do not have the value of `nil' (or the default value, for properties with predefined meanings). - Function: set-extent-property EXTENT PROPERTY VALUE This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a predefined meaning, only certain values are allowed, and some values may be converted to others before being stored.) The following table lists the properties with predefined meanings, along with their allowable values. `detached' (Boolean) Whether the extent is detached. Setting this is the same as calling `detach-extent'. *Note Detached Extents::. `destroyed' (Boolean) Whether the extent has been deleted. Setting this is the same as calling `delete-extent'. `priority' (integer) The extent's redisplay priority. Defaults to 0. *Note priority: Intro to Extents. This property can also be set with `set-extent-priority' and accessed with `extent-priority'. `start-open' (Boolean) Whether the start position of the extent is open, meaning that characters inserted at that position go outside of the extent. *Note Extent Endpoints::. `start-closed' (Boolean) Same as `start-open' but with the opposite sense. Setting this property clears `start-open' and vice-versa. `end-open' (Boolean) Whether the end position of the extent is open, meaning that characters inserted at that position go outside of the extent. This is `t' by default. *Note Extent Endpoints::. `end-closed' (Boolean) Same as `end-open' but with the opposite sense. Setting this property clears `end-open' and vice-versa. `read-only' (Boolean) Whether text within this extent will be unmodifiable. `face' (face, face name, or `nil') The face in which to display the extent's text. This property can also be set with `set-extent-face' and accessed with `extent-face'. `highlight' (Boolean) Whether to highlight the extent when the mouse moves over it. *Note Extents and Events::. `detachable' (Boolean) Whether this extent becomes detached when all of the text it covers is deleted. This is `t' by default. *Note Detached Extents::. `duplicable' (Boolean) Whether this extent should be copied into strings, so that kill, yank, and undo commands will restore or copy it. *Note Duplicable Extents::. `unique' (Boolean) Meaningful only in conjunction with `duplicable'. When this is set, there may be only one instance of this extent attached at a time. *Note Duplicable Extents::. `invisible' (Boolean) If `t', text under this extent will not be displayed - it will look as if the text is not there at all. `keymap' (keymap or `nil') This keymap is consulted for mouse clicks on this extent or keypresses made while `point' is within the extent. *Note Extents and Events::. `copy-function' This is a hook that is run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). *Note Duplicable Extents::. `paste-function' This is a hook that is run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. *Note Duplicable Extents::. `glyph-layout' ('text, 'whitespace, 'inside-margin, or 'outside-margin) The layout policy for this extent's glyph. Defaults to `text'. *Note Annotations::. `begin-glyph' (pixmap, string, or `nil') This extent's begin-glyph. Cannot be non-`nil' at the same time as `end-glyph'. *Note Annotations::. `end-glyph' (pixmap, string, or `nil') This extent's end-glyph. Cannot be non-`nil' at the same time as `begin-glyph'. *Note Annotations::. The following convenience functions are provided for accessing particular properties of an extent. - Function: extent-priority EXTENT This function returns the `priority' property of EXTENT. - Function: extent-face EXTENT This function returns the `face' property of EXTENT. - Function: extent-layout EXTENT This function returns the `glyph-layout' property of EXTENT. - Function: extent-glyph EXTENT This function returns the glyph associated with EXTENT. This is the value of the `begin-glyph' or `end-glyph' property, if either one is non-`nil'. (It is not possible for both to be non-`nil' at the same time.) The following convenience functions are provided for setting particular properties of an extent. - Function: set-extent-priority EXTENT PRI This function sets the `priority' property of EXTENT to PRI. - Function: set-extent-face EXTENT FACE This function sets the `face' property of EXTENT to FACE. - Function: set-extent-layout EXTENT LAYOUT This function sets the `glyph-layout' property of EXTENT to LAYOUT. - Function: set-extent-begin-glyph EXTENT BEGIN-GLYPH &optional LAYOUT This function sets the `begin-glyph' and `glyph-layout' properties of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT defaults to `text' if not specified.) This function will fail if EXTENT already has an END-GLYPH property. - Function: set-extent-end-glyph EXTENT END-GLYPH &optional LAYOUT This function sets the `end-glyph' and `glyph-layout' properties of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults to `text' if not specified.) This function will fail if EXTENT already has a BEGIN-GLYPH property. File: lispref.info, Node: Detached Extents, Next: Duplicable Extents, Prev: Extent Properties, Up: Extents Detached Extents ================ A detached extent is an extent that is not attached to a buffer but can be re-inserted. Detached extents have a start position and end position of `nil'. Extents can be explicitly detached using `detach-extent'. An extent is also detached when all of its characters are all killed by a deletion, if its `detachable' property is set; if this property is not set, the extent becomes a zero-length extent. (Zero-length extents with the `detachable' property set behave specially. *Note zero-length extents: Extent Endpoints.) - Function: detach-extent EXTENT This function detaches EXTENT from its buffer. If EXTENT has the `duplicable' property, its detachment is tracked by the undo mechanism. *Note Duplicable Extents::. - Function: extent-detached-p EXTENT This function returns `nil' if EXTENT is detached, and `t' otherwise. - Function: copy-extent EXTENT &optional BUFFER This function makes a copy of EXTENT. It is initially detached. Optional argument BUFFER defaults to EXTENT's buffer. - Function: insert-extent EXTENT &optional START END NO-HOOKS This function inserts EXTENT from START to END in the current buffer. If EXTENT is detached from a different buffer, or in most cases when EXTENT is already attached, the extent will first be copied as if with `copy-extent'. This function operates the same as if `insert' were called on a string whose extent data calls for EXTENT to be inserted, except that if NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be invoked. *Note Duplicable Extents::. File: lispref.info, Node: Duplicable Extents, Next: Extent Replicas, Prev: Detached Extents, Up: Extents Duplicable Extents ================== If an extent has the `duplicable' property, it will be copied into strings, so that kill, yank, and undo commands will restore or copy it. Note that the extent is not actually copied; rather, a pointer to it is stored, along with the start and end positions of the extent. (This combination is called an "extent replica".) This means that, e.g., if you copy a duplicable extent into the kill ring, then change the properties of the extent, then paste the kill-ring text back into the buffer, the newly-inserted extent will have the property changes you just made to the original extent, and not the property values at the time the text was copied into the kill ring. Specifically: * When a string is created using `buffer-substring' or `buffer-string', any duplicable extents in the region corresponding to the string will be remembered in the string (*note Buffer Contents::.). When the string in inserted into a buffer using `insert', `insert-before-markers', `insert-buffer' or `insert-buffer-substring', the remembered extents will be inserted back into the buffer (*note Insertion::.). The extents can also be retrieved explicitly using `string-extent-data' (*note Extent Replicas::.). * Similarly, when text is copied or cut into the kill ring, any duplicable extents will be remembered and reinserted later when the text is pasted back into a buffer. * An extent replica consists of a pointer to an extent and a range within the string. When an extent replica is inserted into a buffer: - If the original extent was detached from this buffer, it is reattached at the new range. - If the original extent is attached to this buffer and is contiguous with or overlaps the new range, it is simply extended to include that range. Note that in this case the extent's `paste-function' is not called (see below). - If the original extent was detached from another buffer, it is copied as if by `copy-extent' and attached at the new range. - If the original extent is attached to another buffer, or is attached to this buffer and does not overlap the new range, it is copied as if by `copy-extent' and attached at the new range. However, if the extent has the `unique' property, this action is inhibited and nothing happens. * When `concat' is called on strings, the extent replicas remembered in the strings are merged together and placed into the resulting string. * When `substring' is called on a string, the relevant extent replicas are placed into the resulting string. * When a duplicable extent is detached by `detach-extent' or string deletion, or inserted by `insert-extent' or string insertion, the action is recorded by the undo mechanism so that it can be undone later. * Extent motion, face changes, and attachment via `make-extent' are not recorded by the undo mechanism. This means that extent changes which are to be undo-able must be performed by character editing, or by insertion and detachment of duplicable extents. * A duplicable extent's `copy-function' property, if non-`nil', should be a function, and will be run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). It is called with three arguments: the extent and the buffer positions within it which are being copied. If this function returns `nil', then the extent will not be copied; otherwise it will. * A duplicable extent's `paste-function' property, if non-`nil', should be a function, and will be run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. It is called with three arguments: the original extent and the buffer positions which the copied extent will occupy. (This hook is run after the corresponding text has already been inserted into the buffer.) Note that the extent argument may be detached when this function is run. If this function returns `nil', no extent will be inserted. Otherwise, there will be an extent covering the range in question. Note: if the extent to be copied is already attached to the buffer and overlaps the new range, the extent will simply be extended and the `paste-function' will not be called. File: lispref.info, Node: Extent Replicas, Next: Extents and Events, Prev: Duplicable Extents, Up: Extents Extent Replicas =============== The following primitives for manipulating extent replicas are available. An extent replica is used to store extent data in a string and is a primitive data type encapsulating an extent and start and end positions within the string. New extent replicas can be created but there are no mutator functions for modifying existing extent replicas. *Note Duplicable Extents::. Note: Lisp-visible extent replicas may disappear in the future (replaced by allowing `map-extents' to take a string argument). Avoid using the following functions if at all possible. - Function: extent-replica-p OBJECT This function returns non-`nil' if OBJECT is an extent replica. - Function: extent-replica-live-p OBJECT This function returns non-`nil' if OBJECT is an extent replica that has not been deleted. - Function: string-extent-data STRING This function returns the extent data stored along with STRING. The value returned is a list of extent replica objects. - Function: set-string-extent-data STRING DATA This function sets the extent data stored along with a string. `data' should be `nil' or a list of extent replicas. - Function: make-extent-replica EXTENT START END This function makes an extent replica for EXTENT in the range from `start' to `end'. - Function: extent-replica-extent DUP This function returns the extent to which extent replica DUP refers. - Function: extent-replica-start DUP This function returns the start position of extent replica DUP. - Function: extent-replica-end DUP This function returns the end position of extent replica DUP. File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Extent Replicas, Up: Extents Interaction of Extents with Keyboard and Mouse Events ===================================================== If an extent has the `highlight' property set, it will be highlighted when the mouse passes over it. Highlighting is accomplished by merging the extent's face with the `highlight' face. The effect is as if a pseudo-extent with the `highlight' face were inserted after the extent in the display order (*note Extent Endpoints::., display order). - Variable: mouse-highlight-priority This variable holds the priority to use when merging in the highlighting pseudo-extent. The default is 1000. This is purposely set very high so that the highlighting pseudo-extent shows up even if there are other extents with various priorities at the same location. You can also explicitly cause an extent to be highlighted. Only one extent at a time can be highlighted in this fashion, and any other highlighted extent will be de-highlighted. - Function: highlight-extent EXTENT &optional HIGHLIGHT-P This function highlights (if HIGHLIGHT-P is non-`nil') or de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the `highlight' property. (Nothing happens if EXTENT does not have the `highlight' property.) - Function: force-highlight-extent EXTENT &optional HIGHLIGHT-P This function is similar to `highlight-extent' but highlights or de-highlights the extent regardless of whether it has the `highlight' property. If an extent has a `keymap' property, this keymap will be consulted for mouse clicks on the extent and keypresses made while `point' is within the extent. The behavior of mouse clicks and keystrokes not defined in the keymap is as normal for the buffer. File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents Atomic Extents ============== If the Lisp file `atomic-extents' is loaded, then the atomic extent facility is available. An "atomic extent" is an extent for which `point' cannot be positioned anywhere within it. This ensures that when selecting text, either all or none of the extent is selected. To make an extent atomic, set its `atomic' property. File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top Specifiers ********** A specifier is an object used to keep track of a property whose value may vary depending on the particular situation (e.g. particular buffer displayed in a particular window) that it is used in. The value of many built-in properties, such as the font, foreground, background, and such properties of a face and variables such as `modeline-shadow-thickness' and `top-toolbar-height', is actually a specifier object. The specifier object, in turn, is "instanced" in a particular situation to yield the real value of the property in that situation. - Function: specifierp OBJECT This function returns non-`nil' if OBJECT is a specifier. * Menu: * Introduction to Specifiers:: Specifiers provide a clean way for display and other properties to vary (under user control) in a wide variety of contexts. * Specifiers In-Depth:: Gory details about specifier innards. * Specifier Instancing:: Instancing means obtaining the "value" of a specifier in a particular context. * Specifier Types:: Specifiers come in different flavors. * Adding Specifications:: Specifications control a specifier's "value" by giving conditions under which a particular value is valid. * Retrieving Specifications:: Querying a specifier's specifications. * Specifier Tag Functions:: Working with specifier tags. * Specifier Instancing Functions:: Functions to instance a specifier. * Specifier Example:: Making all this stuff clearer. * Creating Specifiers:: Creating specifiers for your own use. * Specifier Validation Functions:: Validating the components of a specifier. * Other Specification Functions:: Other ways of working with specifications. File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers Introduction to Specifiers ========================== Sometimes you may want the value of a property to vary depending on the context the property is used in. A simple example of this in XEmacs is buffer-local variables. For example, the variable `modeline-format', which controls the format of the modeline, can have different values depending on the particular buffer being edited. The variable has a default value which most modes will use, but a specialized package such as Calendar might change the variable so as to tailor the modeline to its own purposes. Other properties (such as those that can be changed by the `modify-frame-parameters' function, for example the color of the text cursor) can have frame-local values, although it might also make sense for them to have buffer-local values. In other cases, you might want the property to vary depending on the particular window within the frame that applies (e.g. the top or bottom window in a split frame), the device type that that frame appears on (X or tty), etc. Perhaps you can envision some more complicated scenario where you want a particular value in a specified buffer, another value in all other buffers displayed on a particular frame, another value in all other buffers displayed in all other frames on any mono (two-color, e.g. black and white only) displays, and a default value in all other circumstances. A "specifier" is a generalization of this, allowing a great deal of flexibility in controlling exactly what value a property has in which circumstances. It is most commonly used for display properties, such as an image or the foreground color of a face. As a simple example, you can specify that the foreground of the default face be * blue for a particular buffer * green for all other buffers As a more complicated example, you could specify that the foreground of the default face be * forest green for all buffers displayed in a particular Emacs window, or green if the X server doesn't recognize the color `forest green' * blue for all buffers displayed in a particular frame * red for all other buffers displayed on a color device * white for all other buffers File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers In-Depth Overview of a Specifier ================================ A specifier object encapsulates a set of "specifications", each of which says what its value should be if a particular condition applies. For example, one specification might be "The value should be darkseagreen2 on X devices" another might be "The value should be blue in the *Help* buffer". In specifier terminology, these conditions are called "locales" and the values are called "instantiators". Given a specifier, a logical question is "What is its value in a particular situation?" This involves looking through the specifications to see which ones apply to this particular situation, and perhaps preferring one over another if more than one applies. In specifier terminology, a "particular situation" is called a "domain", and determining its value in a particular domain is called "instancing". Most of the time, a domain is identified by a particular window. For example, if the redisplay engine is drawing text in the default face in a particular window, it retrieves the specifier for the foreground color of the default face and "instances" it in the domain given by that window; in other words, it asks the specifier, "What is your value in this window?". More specifically, a specifier contains a set of "specifications", each of which associates a "locale" (a buffer object, a window object, a frame object, a device object, or the symbol `global') with an "inst-list", which is a list of one or more "inst-pairs". (For each possible locale, there can be at most one specification containing that locale.) Each inst-pair is a cons of a "tag set" (an unordered list of zero or more symbols, or "tags") and an "instantiator" (the allowed form of this varies depending on the type of specifier). In a given specification, there may be more than one inst-pair with the same tag set; this is unlike for locales. The tag set is used to restrict the sorts of devices over which the instantiator is valid and to uniquely identify instantiators added by a particular application, so that different applications can work on the same specifier and not interfere with each other. Each tag can have a "predicate" associated with it, which is a function of one argument (a device) that specifies whether the tag matches that particular device. (If a tag does not have a predicate, it matches all devices.) All tags in a tag set must match a device for the associated inst-pair to be instantiable over that device. (A null tag set is perfectly valid.) The valid device types (normally `x', `tty', and `stream') and device classes (normally `color', `grayscale', and `mono') can always be used as tags, and match devices of the associated type or class (*note Devices::.). User-defined tags may be defined, with an optional predicate specified. An application can create its own tag, use it to mark all its instantiators, and be fairly confident that it will not interfere with other applications that modify the same specifier - Functions that add a specification to a specifier usually only overwrite existing inst-pairs with the same tag set as was given, and a particular tag or tag set can be specified when removing instantiators. When a specifier is instanced in a domain, both the locale and the tag set can be viewed as specifying necessary conditions that must apply in that domain for an instantiator to be considered as a possible result of the instancing. More specific locales always override more general locales (thus, there is no particular ordering of the specifications in a specifier); however, the tag sets are simply considered in the order that the inst-pairs occur in the specification's inst-list. Note also that the actual object that results from the instancing (called an "instance object") may not be the same as the instantiator from which it was derived. For some specifier types (such as integer specifiers and boolean specifiers), the instantiator will be returned directly as the instance object. For other types, however, this is not the case. For example, for font specifiers, the instantiator is a font-description string and the instance object is a font-instance object, which describes how the font is displayed on a particular device. A font-instance object encapsulates such things as the actual font name used to display the font on that device (a font-description string under X is usually a wildcard specification that may resolve to different font names, with possibly different foundries, widths, etc., on different devices), the extra properties of that font on that device, etc. Furthermore, this conversion (called "instantiation") might fail - a font or color might not exist on a particular device, for example. File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers How a Specifier Is Instanced ============================ Instancing of a specifier in a particular window domain proceeds as follows: * First, XEmacs searches for a specification whose locale is the same as the window's buffer. If that fails, the search is repeated, looking for a locale that is the same as the window itself. If that fails, the search is repeated using the window's frame, then using the device that frame is on. Finally, the specification whose locale is the symbol `global' (if there is such a specification) is considered. * The inst-pairs contained in the specification that was found are considered in their order in the inst-list, looking for one whose tag set matches the device that is derived from the window domain. (The tag set is an unordered list of zero or more tag symbols. For all tags that have predicates associated with them, the predicate must match the device.) * If a matching tag set is found, the corresponding instantiator is passed to the specifier's instantiation method, which is specific to the type of the specifier. If it succeeds, the resulting instance object is returned as the result of the instancing and the instancing is done. Otherwise, the operation continues, looking for another matching inst-pair in the current specification. * When there are no more inst-pairs to be considered in the current specification, the search starts over, looking for another specification as in the first step above. * If all specifications are exhausted and no instance object can be derived, the instancing fails. (Actually, this is not completely true. Some specifier objects for built-in properties have a "fallback" value, which is either an inst-list or another specifier object, that is consulted if the instancing is about to fail. If it is an inst-list, the searching proceeds using the inst-pairs in that list. If it is a specifier, the entire instancing starts over using that specifier instead of the given one. Fallback values are set by the C code and cannot be modified, except perhaps indirectly, using any Lisp functions. The purpose of them is to supply some values to make sure that instancing of built-in properties can't fail and to implement some basic specifier inheritance, such as the fact that faces inherit their properties from the `default' face.) It is also possible to instance a specifier over a frame domain or device domain instead of over a window domain. The C code, for example, instances the `top-toolbar-height' variable over a frame domain in order to determine the height of a frame's top toolbar. Instancing over a frame or device is similar to instancing over a window except that specifications for locales that cannot be derived from the domain are ignored. Specifically, instancing over a frame looks first for frame locales, then device locales, then the `global' locale. Instancing over a device domain looks only for device locales and the `global' locale. File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers Specifier Types =============== There are various different types of specifiers. The type of a specifier controls what sorts of instantiators are valid, how an instantiator is instantiated, etc. Here is a list of built-in specifier types: `boolean' The valid instantiators are the symbols `t' and `nil'. Instance objects are the same as instantiators so no special instantiation function is needed. `integer' The valid instantiators are integers. Instance objects are the same as instantiators so no special instantiation function is needed. `modeline-shadow-thickness' is an example of an integer specifier (negative thicknesses indicate that the shadow is drawn recessed instead of raised). `natnum' The valid instantiators are natnums (non-negative integers). Instance objects are the same as instantiators so no special instantiation function is needed. Natnum specifiers are used for dimension variables such as `top-toolbar-height'. `generic' All Lisp objects are valid instantiators. Instance objects are the same as instantiators so no special instantiation function is needed. `font' The valid instantiators are strings describing fonts or vectors indicating inheritance from the font of some face. Instance objects are font-instance objects, which are specific to a particular device. The instantiation method in this specifier can fail, unlike for integer, natnum, boolean, and generic specifiers. `color' The valid instantiators are strings describing colors or vectors indicating inheritance from the foreground or background of some face. Instance objects are color-instance objects, which are specific to a particular device. The instantiation method in this specifier can fail, as for font specifiers. `image' Images are perhaps the most complicated type of built-in specifier. The valid instantiators are strings (a filename, inline data for a pixmap, or text to be displayed in a text glyph) or vectors describing inline data of various sorts or indicating inheritance from the background-pixmap property of some face. Instance objects are either strings (for text images), image-instance objects (for pixmap images), or subwindow objects (for subwindow images). The instantiation method in this specifier can fail, as for font and color specifiers. `face-boolean' The valid instantiators are the symbols `t' and `nil' and vectors indicating inheritance from a boolean property of some face. Specifiers of this sort are used for all of the built-in boolean properties of faces. Instance objects are either the symbol `t' or the symbol `nil'. `toolbar' The valid instantiators are toolbar descriptors, which are lists of toolbar-button descriptors (each of which is a vector of two or four elements). *Note Toolbar:: for more information. *Note Faces and Window-System Objects:: for more information on fonts, colors, and face-boolean specifiers. *Note Glyphs:: for more information about image specifiers. *Note Toolbar:: for more information on toolbar specifiers. - Function: specifier-type SPECIFIER This function returns the type of SPECIFIER. The returned value will be a symbol: one of `integer', `boolean', etc., as listed in the above table. Functions are also provided to query whether an object is a particular kind of specifier: - Function: boolean-specifier-p OBJECT This function returns non-`nil' if OBJECT is a boolean specifier. - Function: integer-specifier-p OBJECT This function returns non-`nil' if OBJECT is an integer specifier. - Function: natnum-specifier-p OBJECT This function returns non-`nil' if OBJECT is a natnum specifier. - Function: generic-specifier-p OBJECT This function returns non-`nil' if OBJECT is a generic specifier. - Function: face-boolean-specifier-p OBJECT This function returns non-`nil' if OBJECT is a face-boolean specifier. - Function: toolbar-specifier-p OBJECT This function returns non-`nil' if OBJECT is a toolbar specifier. - Function: font-specifier-p OBJECT This function returns non-`nil' if OBJECT is a font specifier. - Function: color-specifier-p OBJECT This function returns non-`nil' if OBJECT is a color specifier. - Function: image-specifier-p OBJECT This function returns non-`nil' if OBJECT is an image specifier. File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers Adding specifications to a Specifier ==================================== - Function: add-spec-to-specifier SPECIFIER INSTANTIATOR &optional LOCALE TAG-SET HOW-TO-ADD This function adds a specification to SPECIFIER. The specification maps from LOCALE (which should be a buffer, window, frame, device, or the symbol `global', and defaults to `global') to INSTANTIATOR, whose allowed values depend on the type of the specifier. Optional argument TAG-SET limits the instantiator to apply only to the specified tag set, which should be a list of tags all of which must match the device being instantiated over (tags are a device type, a device class, or tags defined with `define-specifier-tag'). Specifying a single symbol for TAG-SET is equivalent to specifying a one-element list containing that symbol. Optional argument HOW-TO-ADD specifies what to do if there are already specifications in the specifier. It should be one of `prepend' Put at the beginning of the current list of instantiators for LOCALE. `append' Add to the end of the current list of instantiators for LOCALE. `remove-tag-set-prepend' This is the default. Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the beginning of the current list. `remove-tag-set-append' Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the end of the current list. `remove-locale' Remove all previous instantiators for this locale before adding the new spec. `remove-locale-type' Remove all specifications for all locales of the same type as LOCALE (this includes LOCALE itself) before adding the new spec. `remove-all' Remove all specifications from the specifier before adding the new spec. `remove-tag-set-prepend' is the default. You can retrieve the specifications for a particular locale or locale type with the function `specifier-spec-list' or `specifier-specs'. - Function: add-spec-list-to-specifier SPECIFIER SPEC-LIST &optional HOW-TO-ADD This function adds a "spec-list" (a list of specifications) to SPECIFIER. The format of a spec-list is `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' where * LOCALE := a buffer, a window, a frame, a device, or `global' * TAG-SET := an unordered list of zero or more TAGS, each of which is a symbol TAG := a device class (*note Devices::.), a device type, or a tag defined with `define-specifier-tag' * INSTANTIATOR := format determined by the type of specifier The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A list of inst-pairs is called an "inst-list". The pair `(LOCALE . INST-LIST)' is called a "specification". A spec-list, then, can be viewed as a list of specifications. HOW-TO-ADD specifies how to combine the new specifications with the existing ones, and has the same semantics as for `add-spec-to-specifier'. In many circumstances, the higher-level function `set-specifier' is more convenient and should be used instead. - Function: set-specifier SPECIFIER VALUE &optional HOW-TO-ADD This function adds some specifications to SPECIFIER. VALUE can be a single instantiator or tagged instantiator (added as a global specification), a list of tagged and/or untagged instantiators (added as a global specification), a cons of a locale and instantiator or locale and instantiator list, a list of such conses, or nearly any other reasonable form. More specifically, VALUE can be anything accepted by `canonicalize-spec-list'. HOW-TO-ADD is the same as in `add-spec-to-specifier'. Note that `set-specifier' is exactly complementary to `specifier-specs' except in the case where SPECIFIER has no specs at all in it but `nil' is a valid instantiator (in that case, `specifier-specs' will return `nil' (meaning no specs) and `set-specifier' will interpret the `nil' as meaning "I'm adding a global instantiator and its value is `nil'"), or in strange cases where there is an ambiguity between a spec-list and an inst-list, etc. (The built-in specifier types are designed in such a way as to avoid any such ambiguities.) If you want to work with spec-lists, you should probably not use these functions, but should use the lower-level functions `specifier-spec-list' and `add-spec-list-to-specifier'. These functions always work with fully-qualified spec-lists; thus, there is no ambiguity. - Function: canonicalize-inst-pair INST-PAIR SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given INST-PAIR. SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for an inst-pair, i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator is given a tag set of `nil' (the empty set), and a single tag is converted into a tag set consisting only of that tag. If NOERROR is non-`nil', signal an error if the inst-pair is invalid; otherwise return `t'. - Function: canonicalize-inst-list INST-LIST SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given INST-LIST (a list of inst-pairs). SPECIFIER-TYPE specifies the type of specifier that this INST-LIST will be used for. Canonicalizing means converting to the full form for an inst-list, i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a single inst-pair or any abbrevation thereof or a list of (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) If NOERROR is non-`nil', signal an error if the inst-list is invalid; otherwise return `t'. - Function: canonicalize-spec SPEC SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given SPEC (a specification). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for a spec, i.e. `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a possibly abbreviated inst-list or a cons of a locale and a possibly abbreviated inst-list. (See `canonicalize-inst-list'.) If NOERROR is `nil', signal an error if the specification is invalid; otherwise return `t'. - Function: canonicalize-spec-list SPEC-LIST SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given SPEC-LIST (a list of specifications). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for a spec-list, i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This function accepts a possibly abbreviated specification or a list of such things. (See `canonicalize-spec'.) This is the function used to convert spec-lists accepted by `set-specifier' and such into a form suitable for `add-spec-list-to-specifier'. This function tries extremely hard to resolve any ambiguities, and the built-in specifier types (font, image, toolbar, etc.) are designed so that there won't be any ambiguities. If NOERROR is `nil', signal an error if the spec-list is invalid; otherwise return `t'. File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers Retrieving the Specifications from a Specifier ============================================== - Function: specifier-spec-list SPECIFIER &optional LOCALE TAG-SET EXACT-P This function returns the spec-list of specifications for SPECIFIER in LOCALE. If LOCALE is a particular locale (a buffer, window, frame, device, or the symbol `global'), a spec-list consisting of the specification for that locale will be returned. If LOCALE is a locale type (i.e. a symbol `buffer', `window', `frame', or `device'), a spec-list of the specifications for all locales of that type will be returned. If LOCALE is `nil' or the symbol `all', a spec-list of all specifications in SPECIFIER will be returned. LOCALE can also be a list of locales, locale types, and/or `all'; the result is as if `specifier-spec-list' were called on each element of the list and the results concatenated together. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are returned. (The default value of` nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be returned. - Function: specifier-specs SPECIFIER &optional LOCALE TAG-SET EXACT-P This function returns the specification(s) for SPECIFIER in LOCALE. If LOCALE is a single locale or is a list of one element containing a single locale, then a "short form" of the instantiators for that locale will be returned. Otherwise, this function is identical to `specifier-spec-list'. The "short form" is designed for readability and not for ease of use in Lisp programs, and is as follows: 1. If there is only one instantiator, then an inst-pair (i.e. cons of tag and instantiator) will be returned; otherwise a list of inst-pairs will be returned. 2. For each inst-pair returned, if the instantiator's tag is `any', the tag will be removed and the instantiator itself will be returned instead of the inst-pair. 3. If there is only one instantiator, its value is `nil', and its tag is `any', a one-element list containing `nil' will be returned rather than just `nil', to distinguish this case from there being no instantiators at all. - Function: specifier-fallback SPECIFIER This function returns the fallback value for SPECIFIER. Fallback values are provided by the C code for certain built-in specifiers to make sure that instancing won't fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that faces other than `default' inherit their attributes from `default'). By design, you cannot change the fallback value, and specifiers created with `make-specifier' will never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance). The fallback value will be an inst-list that is instanced like any other inst-list, a specifier of the same type as SPECIFIER (results in inheritance), or `nil' for no fallback. When you instance a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See `specifier-instance'.